This is freeware. It may be freely distributed provided the copyright and the contents of all files are unmodified. The usual caveats apply, i.e., use at your own risk, etc. etc. <g>
***********************************
Note: read at least 0-4.
Contents
0) Warning
1) QuickStart Guide
2) Basic things you need to know about Xnews.
3) How do I...
4) Hidden keyboard shortcuts / Keyboard tips
5) Troubleshooting / FAQs
6) What does ____ do?
7) Hidden Tips and Tricks
8) Filters, filters everywhere
9) Header and article storage
10) Folders
11) Advanced customizations (groups.ini)
12) Plonk file
13) Score file.
14) Regular expression.
***********************************
0) Warning:
This is betaware, so don't use it unless you like to mess around with software. There is no documentation aside from this longish readme.
This is an on-line reader. It has pseudo offline features such as header storage, but if you need true off-line capabilities, use Agent, Gravity, or some other reader.
I'm a fan of NewsXpress so I liberally stole ideas from that program. NX users should find Xnews very familiar.
About this document: I know it's rather minimal but please read it. I'm too lazy to write a full blown manual. I assume you have used other newsreaders before and basically know how usenet works, so I will only go over things that are different about/specific to Xnews.
***********************************
1) QuickStart Guide
First time you run Xnews, it will bring up the Setup dialog. Enter your name, etc. I'll only describe the unfamiliar items here:
Public Email: This is the email you want to put in your From: header when
posting to usenet. In contrast. Email is the email you want to
to use when replying via private email.
Why use separate emails for usenet and mail? I do it to help
deal with spam.
IDToken This is a string Xnews embed in Message-ID in order to track your
posts and alert you to replies to your articles.
You can use any string of letters and numbers. I use my email
without the @ and . i.e., luutrangeocitiescom
The idea is to use a string that noone else is likely to use.
Once you've done that, click Okay. Xnews will ask you to create a server profile. (The program can deal with multiple servers.) Enter the server name, e.g., news.mindspring.com. Then enter an alias or title for the server, e.g., Mindspring. The alias is what will appear on the menu.
That's it. You should now say yes when it asks if you want to retrieve the newsgroup list. Kick back, and enjoy.
***********************************
2) Basic things you need to know about Xnews.
First, a bit of terminology: when I say "groups window", I mean the window that lists all the groups in a server. "articles window" refers to the window that lists all articles in a group and also displays the selected article.
The groups window:
- You can select multiple items in the group and article listing the same way you do in Windows Explorer, with Ctrl and Shift.
- While the All tab is selected, enter a filter string in the edit box at the bottom to see only groups whose name contain that string. You can do the same in the articles window, except here, the filter string is assumed to be a regular expression.
- You can resize the columns in both groups and articles windows. Drag and drop drop the column header to reorder the columns,
The articles window:
- The article listing and viewer _share the same window_ (unlike in NewsXpress). You can switch between full / split view by hitting F12. When in full view, hit return to move back and forth between the viewer and list. You can do the same by selecting View | Switch List <-> Viewer or by clicking on the second panel at the bottom.
- When you're in split view, single click on the subject to read the article. (Click on any other column to avoid opening the article.) When you're in full view, you need to double click. In either case, pressing Return will do the same.
- When the focus (cursor) is in the list, if you click Goto next(/prev/...), it will move to the next(/prev/etc) article relative to where the selection bar (curaor) is. If the cursor is in the viewer, it will move to the next(/prev/etc) article relative to the article you're reading, regardless of where the selection bar in the list may be. That makes ense, doesn't it. To move the selection bar to the article you're reading, press 'c' or click on the progress bar (gauge) at the bottom.
- In order to reply/followup/forward a message, you _must first open (read) it_. Furthermore, the focus (cursor) has to be in the viewer.
General:
- You can customize the keyboard (Alt+K). This is also a good way to look at the list of current shortcuts, not all of which are visible on the menus.
- There is no connect/disconnection button. The program just connects when it needs to and disconnects when you close a group window or shut down the program. Try to avoid opening too many simultaneous connections, since this is not good for the news server. (If the program is busy doing something and you open another group or read an article or update message count, etc., it will have to open another connection.) Xnews itself doesn't have any restriction in this regard; however, some servers actually restrict you to X number of simultaneous connections.
- Xnews supports multiple servers. You can even open several servers at once, in the same window. Note: avoid running multiple copies of Xnews simultaneously. Not only does this waste memory, it can lead to newsrc and folder conflict and cause all sorts of weirdness.
- You can define multiple identities with different names, email, and sig (signature) file via the Setup dialog. When posting an article, you can then select which identity to use. You can also specify which identity to use with certain servers/newsgroups (read on).
- You can customize certain settings for individual server. For example, in server A, you can use identity X; in server B, you can use identity Y. It should be obvious in the Setup dialog how this is done.
- Similarly, you can customize certain settings for individual group or groups. You may have noticed that when you are in a group with "binaries" in the name, the display looks a bit different. For example, all the threads are not automatically expanded. This is the result of certain settings in groups.ini. Unfortunately, you do have to edit the groups.ini file for group-based customizations. See the section titled "Advanced customizations".
- Xnews stores most settings in ini files which you can edit directly. The main ones are:
xnews.ini - global settings
servers.ini - server info and per-server custom settings.
groups.ini - per-group custom settings
You really only need to edit groups.ini manually. Use the setup dialog for the others.
- I wrote Xnews for *me* to use. The program heavily reflects my preferences, habits, and sensibility. Yes, extensive end-user research went into the making of this software, albeit it's only of 1 user. The interface is a bit quirky and the program has that freeware feel to it. If you think Microsoft represents the apotheosis of good software design, this program is probably not for you. If not, you may learn to like it -- or not. It's free, so what the hey.
That said, if there's something you want to see added/changed, it doesn't hurt to ask. Provided that the change will result in the greatest happiness to the greatest number of people while causing the least amount of pain to me, I may just do it.
Cheers.
***********************************
3) How do I...
Q: ... retrieve the last n headers from a newsgroup.
A: Instead of pressing Return to open the group, press Ctrl+Return. This will bring up a dialog that lets you select how many headers to retrieve. This is useful for sampling a group with a huge number of headers. When in the article window, you can bring up this dialog by selecting Article | Refresh Headers Special (Ctrl+F5). For example: press Ctrl+Return open a group and specify 100 headers to retrieve. Xnews will retrieve the newest 100 headers. Then you decide you want to read the older articles. Hit Ctrl+F5, then move the slider back to the left until you get the number of headers you want, or all the way to the left to get everything.
Q: ... decode/save/transfer several articles at once?
A: Xnews uses a queueing system. To put an article into the queue, press Space. Pressing space again removes it from the queue. When you queue an article, you will see a number indicating its queue order in the Q column. Now, select Article | Decode/Save as... or Transfer | (folder). You can also queue/dequeue an entire thread at a time.
Q: ... decode multipart binaries?
A: By default, Xnews performs multipart threading in groups that have "binaries" in the name (much like NewsXpress does). Multipart threading means it will put all the parts of a file and roll it under a thread. If a file has all the parts, you will see a 4-block cube icon next to it; if it has one or more missing parts, the cube will have a missing block. Also, if you look at the lines column, it will tell you exactly how many parts there are and how many are present.
To queue a multipart file, just select the thread (with the block icon), and hit space. Xnews will tag all the individual parts for you. Then hit decode.
Hint: with certain file types, it's possible to "sample" the file this way: expand the multipart thread, then individually queue a few parts, e.g., 1/10, 4/10, 8/10 You _must_ queue the first part. This works well for, say, mp3 files but obviously not zip files as they will be corrupted and unreadable. (Caveat: I think "sampling" doesn't work for MIME-encoded files.)
Q: ... cancel a message?
A: To cancel a message, you have to find it and retrieve it first. You can do this by opening the group as usual, or by using XPAT search (see next section).
Q: ... use XPAT search?
A: Most servers have a function called XPAT search, which performs server-side search for articles (in other words, search what's on the server, as opposed to what you have on the screen). To do a search, select which field, or header, you want to search on. Most of the time, you probably want to search by author or subject. The search string is a Unix wildmat, which means unless you want to search for an exact string, you want to surround the string with wild cards (asterisks). For example, if you enter "help" (without quotes), you won't turn up anything unless there's an article with the exact subject "help". Instead, type "*help*". On the other hand, there's no need to type "*[Hh][Ee][Ll][Pp]*" (case insensitive search) because (thank goodness) the program will do that for you.
***********************************
4) Hidden keyboard shortcuts / Keyboard tips
Most shortcut keys are either shown on the menus or listed in the keyboard mapping dialogs. These are shortcuts that are NOT.
In articles window:
Space Queue/Dequeue article/thread (place in queue)
Shift+Space Queue/Dequeue article/thread, but put in head (instead of tail) of the queue
Ctrl+Space Queue everything in sight (WARNING: does NOT tag multipart binaries intelligently)
Ctrl+Shift+Space Clear queue
Ctrl+Up/Down Resize the split window.
In article viewer:
Space page down
Backspace page up
Return switch to article listing
Num 1..Num9 (number1 through 9 on the keypad). If using split screen, scroll the list while the cursor is in the viewer.
In groups window:
Ins manually add a group (right click on name column to edit name)
Del permanently delete selected group(s) from the newsrc
F4 Switch between subscribed/all groups
There shortcuts are in the keyboard map dialog but I'll list them here just in case.
In article listing and viewer
? / previous / next unread
> . previous / next article (read or unread)
< , previous / next queued article
; ' previous / next thread
\ next article with 9999 score (see scoring.txt)
` (backquote) next new article since last stored header retrieval
(see the section on storage)
Alt+Left Go back in history
Alt+Right Go forward in history
A few words on remapping the keyboard.
- You have to be in the groups window or articles window to change their respective shortcuts. Since these two windows are never active at the same time, it's okay to assign the same key to two functions not in the same window. for example, you can assign Ctrl+P to "Post" in the groups window and "Print" in the articles window.
- Don't assign an unshifted letter key [0..9,a-z] in the groups window, as this will interfere with the feature that lets you jump to a line in the list by typing the first few letter.
- The program is pretty liberal about letting you assign any key you want to any function, but be careful about assigning keys that have certain functions in normal Windows programs such as the cursor keys or Ctrl+F6 (switch to next window). Feel free to experiment, though.
- You can't assign to the Del key; the Windows hotkey control won't let you. If you really want to do this, edit the keys.ini file manually.
***********************************
5) Troubleshooting
Q: When I try to post something, I get "bad message ID" error from the server.
A: Try using a shorter IDToken (Setup | Identity). If that doesn't work, remove the IDToken.
Q: When a child window is maximized, why is its close (X) button grayed out?
A: It's a bug in the Delphi library. The close button only LOOKS disabled; you can still click on it and it will close the window. Pressing ctrl+F4 or Esc also works.
Q: All my buttons are weird / messed up / invisible.
A: Make sure you're using the right comctl32.dll. Download it here.
On systems with win98 + video cards with nVidia or S3 chips, there seems to be a problem with bitmap corruption in programs that use image lists. Hopefully, the companies in question will fix this with new drivers.
Q: I got "Access violation in _____" when I ______
A: You found a bug. Email me and tell me exactly what you were doing when you got the error. Try to reproduce the error if you can.
Q: Why is it that the get parent article commands, when successful, sometimes inserts the found article in the listing and sometimes does not?
A: Xnews relies on the message number to insert articles into the list. If it doesn't show the found parent article in the list, it means that the server did not return the message number (the server assigns a number to every article in a group). I don't know enough about server software to explain why, but that's how it is.
Q: How come when I close an articles window, sometimes the program update the message count and sometimes it doesn't?
A: Xnews considers automatically updating the message count a low priority task, so if there's no available connection, it doesn't do it. Of course you can force it by pressing F5.
***********************************
6) What does ________ do?
Q: Mark keep/unkeep?
A: If you do not have storage on, when you do a catchup, the next time, you will not see the headers you've retrieved. If you mark an article or thread as keep, the program will retrieve it again the next time, even if you did a catchup. When you keep something, it automatically gets assigned a high score so it'll stand out next time you
One example where this is useful is when you have a multipart binary with some parts missing. If you do a catchup, next time you may retrieve the missing parts, but then the parts you had before will now be gone. In this case, you want to keep those parts you have and hopefully get the rest next time.
If you are storing headers, kept articles are never deleted except when they expire on the server. That is, they are protected against deletion and local expiration (the expiration you set in the Storage Options dialog). If you want to delete a kept article, you must first unkeep it.
You can specify what score to automatically assign to kept articles in Setup | Misc. If you set this to zero, no score will be assigned to kept articles.
Q: High score/0 score?
A: This is equivalent to marking something as important/not important. It simply assigns a score of 9999 or zero to selected threads/articles. You can then right click on the Score column (or select View | Filter Scores) and select a score filter to view only high scored articles.
Q: AutoBrowse?
A: The AutoBrowse feature automatically opens an article when you move the highlight (selection) bar over it in the listing, provided the article is in the cache (or folder). Autobrowse has no effect unless you are in split screen mode. You can turn Autobrowse on and off manually at any time (under View menu). In adition, you can control when it should be on by default. Set AutoBrowseOpt in Xnews.ini under [Misc] section as follows: 0 = never; 1 = when viewing folder or storage of article body is on; 2 = always.
Q: What's with all the catchup options?
A: Traditionally, "catchup" in newsreaders means to update the read count to the last article seen. If you look at the newsrc, you'll see a bunch of number like
1-50,55,65-80.
Each article is assigned a number by the server, and these numbers in the newsrc indicate which articles you have read. When you do a catchup, the program sets this to
1-<highest-numbered article retrieved>
"Catchup" basically means "okay, I've seen all I care to. Don't show me these articles next time." Note that you may not have actually read all these articles; you just want to treat it as if you did.
In the articles window, there are 3 catchup options (all of which will close the window):
- Catchup: this does what's described above.
- Catchup and clear keep: this does the above and removes any kept articles as well. Keeping articles is an Xnews feature described above.
- Catchup and Kill XPost: this is equivalent to issuing a mark all as read command then closing window. Mark all as read is NOT the same as catchup since catchup only sets the read count (i.e., it sort of fakes it) whereas Mark all as read go through each article and mark it read, as if you have actually read it. This does 2 things: 1) Mark as read will perform crosspost killing in subscribed groups. That is, if the same article was crossposted to another group you subscribe to, then it'll be mark as read there too. and 2) If you have storage on, the next time you retrieve headers, the old articles will show up as read. This last option is slower than the first two. How much slower depends on the amount of crosspost and number of articles.
Whew! Was that confusing enough?
In the groups window, there are separate catchup and clear keep commands. Note that in order to do a catchup, you must have updated the message count once. The "Clear read and keep" command simply clears out the newsrc entry for the selected group(s), letting you essentially start anew.
***********************************
7) Hidden tips and tricks:
- Pay attention to the pop up hints.
- In groups window, you can right click on the group name or rc column to edit. To retrieve a specified number of headers, press Ctrl+Enter instead of Enter to open a newsgroup.
- If you want to select an article without opening it, click on any column OTHER than the subject column.
- Use the filter box at the bottom (I'll call this the B filter for convenience). For example, type in news.*ex|nx and press Enter to see only articles about NX in news.software.readers. You can even type in a filter while it's retrieving headers.
- In the article viewer, double click on a URL or article reference to launch the URL or load the reference. (Or place the caret on the URL and press Ctrl+Enter.)
- In the article viewer, select text with the mouse; when you release the mouse button, the text is automatically copy to the Windows clipboard.
- If you hold down the Ctrl key while opening an article, the program will just retrieve the headers. This is useful when you want to see only the headers of a very long article, or if you want to post a followup to an article without retrieving the whole body.
- You can drag newsgroup names from the newsgroups window and drop them onto the Newsgroups or Followup-To fields in the message editor.
- If you hold down the shift key while clicking on a server (Server menu), you'll be placed in the Setup dialog to edit properties of that server.
- In split screen, you can scroll the list even when the cursor is in the viewer this way: turn on Num Lock and use the arrows, home / end, pgup / pgdn as usual. Use the Num 5 key to open the selected article.
- I know my documentation is crappy (heh, it's just a hobby project). If you don't understand something, email me and ask questions. Don't just sit there and curse the monitor (or me :)
***********************************
8) Filters, filters everywhere
You've already seen the filter box in the groups and articles window, where you can type in a string to show only groups or articles whose names or subjects contain the string. In the articles window, the filter box at the bottom is pretty nifty. (I'll call this the B filter for convenience.) You can use a regex (regular expression) in the B filter. In adition, if you want to filter on the author (from) column instead of the subject, right click to the right of the filter box (or press Ctrl+F). The letter should change from S (subject) to F (from). When you are in a folder, you can also switch to G (group) and view only articles from certain groups.
There are some subtleties which I should point out. As you type in a regex, you'll see the result immediately. The list is not yet threaded. To thread it, press Return. Doing this sort of "locks" the filter in place. If you select another filter (see below), or type in another regex, the filter will be applied on top of the current list, i.e., what you see on the screen. On the other hand, you can undo the current filter by selecting View | Undo last filter or by pressing Backspace or Delete to clear the B filter _before typing anything else_.
There are also predefined filters you can apply. They are
- hide incomplete binaries: hide binaries with missing parts/
- show queued articles only: show only articles that are currently in the queue. Note: previously queued articles that have been processed will not be shown.
- show new headers only: This is only meaningful with storage turned on. When you're storing headers, you will have a lot of headers and it may be hard to tell which are new. This filter will show you only headers that are new since the last session, or more accurately, since last time you opened the window.
The others are obvious.
To remove the filter and view all articles, select View | Remove All Filters or left click to the right of the edit box (where the letter S/F/G is). You can also undo the last filter and invert the filter.
Wait, there's more.
In the article list, click anywhere on the score column to bring up a menu that lets you do a filter based on score. The choices are:
>=9999: show only "important" articles
>0: show positive scores
>=0: show non-negative scores.
>-9999: show only those not killed (negative allowed)
Clear: remove filter.
There's also a filter dialog (f9) that lets you set a filter based on one or more criteria. First check one or more fields you want to filter on, then enter the appropriate condition.
Note that all the filters are cumulative, i.e., they're applied to what's currently in visible in the list, which may br the result of previous filters and may not be the full set of available articles. The exception is the filter dialog, where you can choose whether to apply the filter on top of the current filters by checking the box "Add to existing". Otherwise, if you want to apply a filter to the original set of articles, you must first remove the filter.
Finally, the last filter you applied will affect incoming articles when you refresh headers. For example, if you click B (hide incomplete binaries), then F5 (refresh), after the headers are loaded and the articles get threaded, any NEW binaries that are incomplete will be filtered out as well and you won't see them until you remove filter.
Here's an example of how you can use filters: assuming you have header stored, after you open alt.tv.x-files, press N. This shows just the new headers. then type in dream.*land (match "dream land" or "dreamland") in the B filter and press return to view articles about the "Dreamland" episode. Then browse through the list and mark the threads/articles you like with the '9' key. This sets their score to 9999. Now click on the score column and select >0 or >=9999 to see the articles you just tagged and any others scored by your score file.
***********************************
9) Header and article storage.
As I menioned earlier, Xnews is an on-line newsreader. It does cache articles within a session so that when you re-read an article, it just reloads the article from the cache instead of getting it from the server again. When you close the window, the cache is purged by default.
Once in a while, though, when you quit in the middle of reading a busy group, you don't want to do a catchup since you're not done yet, but you don't want to have to retrieve a lot of headers next time. This is what the Storage feature is for. Storage is basically just a more permanent cache.
Press F7 in the articles window. You'll have the option to storee the headers only or both headers and article bodies. You can also specify an expiration so that articles older than X days are automatically purged. If you select never expire, than the articles are removed when they expire on the server.
For efficiency reasons, when an article is removed from storage, it's not actually deleted but only marked as deleted. Thus, the size of the file remains the same. To reclaim disk space, hit F7 then click the "Compact" button.
Note #1: with storage, you can tell the new headers from the stored ones by black lines through their icons (stored headers have blank icons). Hit the ` (backquote) key to jump to the next unread, new article. Also, if the article itself (not just the header) has been stored, then the icon is yellow.
Note #2: on the toolbar, there's an icon indicating the current storage option. Click it for a quick way to change the atorage option.
***********************************
10) Folders
Storage is only semi-permanent. Articles will be purged when they expire on the server, or when they're older than the expiration date you set. For permanent storage of articles, use folders, a.k.a. mailboxes.
Use the setup dialog to add or remove folders. Once you've set up a folder, you can transfer articles into it for permanent storage. I already setup a folder called "Archive" for you.
As with NewsXpress, you can define a default folder where articles should be transferred when you click the archive button. Goto Setup | Folders. You should see a folder with a red dot next to it in the list box. The dot indicates the default folder. Click on the space to the left of a folder name to make it the default folder.
Advanced tricks:
#1: you can override the default folder on per-group (edit groups.ini) or per-server (Setup | Servers) basis.
#2: if you want the program to transfer articles into a folder of the same name, open xnews.ini and under [Misc] change
Archive=xxx
to
Archive=*
(That's an asterisk). Ditto in servers.ini and groups.ini.
#3: you can share folders with NewsXpress. Just point to the file in Setup | Folders. Note: because Xnews keeps an index file, if what's in the index (.hdr) does not match what's in the folder (.mbx) file, Xnews will have to rebuild the index.
***********************************
11) Advanced customizations
The settings in xnews.ini (Name, Email, etc.) are essentially global settings. It's possible to override these settings for individual or group of groups. However, you need to manually edit the groups.ini file to do this.
You can override settings in xnews.ini for an individual group or hierarchy by putting them under a section in groups.ini for said group or hierarchy. Setting in groups.ini override those in servers.ini, which in turn override those in xnews.ini. The following settings may be overriden in groups.ini:
Name
Email
PublicEMail
IDToken
Organization
SigFile
MultipartThreading
SortOn
SortOrder
ColumnLayout
ExpandAllThreads
FullScreen
AttachDir
DecodeDir
Archive
Hint: open xnews.ini and look at how these values are set. Read the comments.
For example, say you want to use the sig file mysig.txt most of the time; when in a comp group, you want to use worksig.txt, unless you are in a comp.lang.pascal.delphi.* group, in which case you want to use delphisig.txt.
In xnews.ini:
[ID]
Name=my name
; etc.
SigFile=mysig.txt
In groups.ini:
[comp.*delphi]
SigFile=delphisig.txt
[^comp]
SigFile=worksig.txt
Note that the program processes groups.ini in sequential order and stops once it finds a match. Also, there's no need to replicate the other settings such as name or email as they simply revert to the values set in xnews.ini (unless of course you want to use a different name or email).
Occasionally, you may want the program to continue on to the next section in groups.ini. To do this, add continue=1 to the current section. Take the example above. Suppose you want to use some set of email, name, etc. for all comp groups. In addition, you want to use a different sig file for delphi groups. This will do the trick:
[^comp]
SigFile=worksig.txt
Email=whatever
Name=whatever
; etc.
continue=1
[comp.*delphi]
SigFile=delphisig.txt
; inherit email, name, etc. from comp section
Note: the section name is indeed a regex. Because groups.ini is a windows ini file, you can't use [ ] in your regex. In this case, just use a dummy value then add a regex= line. For example, since you cannot write
[delphi[^a]]
...
(match delphi, but not philadelphia)
You have to write
[compdelphi]
regex=delphi[^a]
...
Finally, you can set up xnews for multiple users by specifying a different start up directory with the command line switch /d:start-up-dir. (Note: you cannot have any space between the switch and the directory name.) For example,
c:\bin\xnews.exe /d:c:\user\mary
mary can then have her own .ini files, score file, etc.
***********************************
12) Plonk file
The plonk file is just a quick way to kill an annoying poster. It is not as powerful and flexible as the score file. You cannot use regular expressions, so the poster's name and email must match exactly (except for case). Also, it is global (you cannot filter by groups). On the other hand, it's simpler to use than the score file and is also more efficent.
Usage: when reading an article, press 'k' to add the poster to the plonk file. You can bring up the plonk file viewer with Ctrl+k. You can then add, remove, or edit entries.
The plonk file itself is just a plain text file. Each line consists of
name<tab>email
that is, a name, followed by a tab, then email, all in lower case. The list is sorted but that is only for the benefit of the human reader (the program uses a hash lookup so it doesn't care). The tab character is crucial, so be careful if you choose to edit the file manually.
***********************************
13) Score file.
Xnews happily steals the scoring system concept from slrn. Basically, each article is assigned a score from -9999 to 9999. By default, an article has score 0 (no score, or neutral). Articles with score of -9999 or less are killed (you'll never see them, unless you turn off hard kill, in which case they show up with a red X icon). Articles with score of 9999 or more are considered "important" and flagged with a yellow ! icon. Read scoring.txt for details.
***********************************
14) Regular expression
I've mentioned regular expression (abbrev. regex) throughout the readme. regex is used for the filters, folder search, and score file. You may wonder what regex syntax Xnews supports.
Xnews uses Philip Hazel's PCRE (Perl Compatible Regular Expression) package, adapted for Delphi by yours truly. What this means is that you have access to a very powerful regex engine, and if you're already familiar with Perl, all the better. PCRE supports most contructs in perl regex.
Here's a good introductory tutorial on perl regex:
I've helpfully added a feature to let you try out Xnews' regex engine and see how it works. Select Special | Test Regex.
For the full discussion on PCRE and differences between PCRE and perl regex, read pcre.html. This doc is aimed at programmers and will probably give you a headache. (It does me.) So here's a crib sheet, which may suffice:
1) Letters, numbers, and non-special characters just match themselves.
Example:
color
match anything with the word color in it
2) Special characters:
\ treat next character literally, i.e., as itself and not a special
character.
. match any character
^ match begin of string
$ match end of string
| alternative
(..) grouping
[..] match one of the characters in the set
[^..] does NOT match one of the characters in the set.
(the .. are ellipses, not two literal periods.)
Example
help\.
matches help followed by a period
ca.s
matches "cats" "cars"
^test
matches "testing", "tester", but not "the test"
me$
matches "see me" but not "meter" or "me and you"
cat|mouse
matches "cat" "mouse"
dog(s|gie)
matches "dogs" "doggie"
[aeiou]
matches a vowel
[a-z0-9]
matches a letter or digit. Note how the - is used to specify a range.
if you want to specify a dash as part of the set, put it at the
beginning or end, e.g. [a-f0-9-] matches a-f, 0-9, or dash.
Note: when I say "help\." matches "help" followed by a period, what I really means is that the regex will successfully match with a string that contains "help" followed by a period. Thus "please help. now" will also match, although of course the matching part is only "help." On the other hand, the regex "^help\.$" will only match the string "help." since the ^ and $ must match the start and end of string.
3) Quantifiers (match how many times)
* Match 0 or more times
+ Match 1 or more times
? Match 1 or 0 time (i.e., optionally match)
{n} Match exactly n times
{n,} Match at least n times
{n,m} Match at least n but not more than m times
Example
ma+
matches "ma" "maaa" "maaaaaaa"
ma*
matches "m" "maaa"
(yada ){2,}
matches "yada yada yada "
foo(and)?bar
matches "fooandbar" or "foobar" (the "and" is optional).
4) Shorthands for character set
\w Match a "word" character, letters, numbers, and "_"
\W Match a non-word character, opposite of \w
\s Match a whitespace character (space, tab, cr, lf)
\S Match a non-whitespace character, opposite of \s
\d Match a digit character
\D Match a non-digit character
Example
\(\d\d\d\)\s*\d\d\d[- ]?\d\d\d\d
match a U.S. phone number
that is, 3 digits enclosed in literal parenthesis
then zero or more spaces
then 3 digits prefix
then either a dash or a space or nothing at all
then 4 digits.
5) Zero width assertion
A fancy way of saying a true condition that doesn't actually match or consume a character.
\b Match a word boundary
\B Match a non-(word boundary)
Example
\bfoot
match "footer" "footing" "a foot" but not "afoot"
foot\b
match "afoot" and "foot." (period doesn't count as part of word)
but not "footing"
\bfoot\b
match the whole word foot
foot\B
match "footer" but not "foot;" i.e., there's got to be something
after foot that is part of a word
6) Back references
If your regex contains one or more subexpression (..) you can refer to the <digit>th subexpression with \<digit>
Example
(\b\w+\b) to \1
match "man to man" "hand to hand" "100 to 10000"
the \b\w+\b matches a whole word. The ( ) saves the word
in subexpression #1 (it's the first sub expression in the regex).
The \1 refers back to it.
"man to child" would not match since child does not match man.
Note: Xnews allows up to 19 sub expression in a regex.
7) Look ahead/behind
(?=regexp) lookahead assertion.
(?!regexp) negative lookahead assertion.
(?<=regexp) look behind assertion
(?<!regexp) negative look behind assertion
Example
\w+(?=\t)
match a word followed by a tab; the tab isn't included in the match
foo(?!bar)
match any occurrence of "foo" that isn't followed by "bar"
(?<!foo)bar
match an occurrence of "bar" that is not preceded by foo
8) Case sensitivity
In Xnews, the filter regex is always case insensitive. In the score file, you can make regex case sensitive by specifying Keyword= expression rather than Keyword: expression. In the folder search dialog, you can toggle case sensitivity by checking the "Match case" box.
